/**
 * @file mp3.c
 * @brief 提供播放MP3文件的基本功能
 * @details 该文件定义了一个MP3文件列表，并提供一个函数
 * 通过调用外部命令行工具 'mpg123' 来播放指定的音频文件。
 * @version 1.0
 * @date 2025-07-05
 */
#include <stdio.h>
#include <stdlib.h> // 包含 system() 函数的定义
#include "mp3.h"    // 包含此模块的头文件声明

/**
 * @brief 存储MP3文件路径的全局常量数组
 * @details 定义了一个包含12个MP3文件路径的列表。
 * 这些路径是相对于程序执行位置的相对路径。
 */
const char *mp3_file[12] =
    {
        "./res/audio/d1.mp3",
        "./res/audio/d2.mp3",
        "./res/audio/d3.mp3",
        "./res/audio/d4.mp3",
        "./res/audio/d5.mp3",
        "./res/audio/d6.mp3",
        "./res/audio/d7.mp3",
        "./res/audio/d8.mp3",
        "./res/audio/d9.mp3",
        "./res/audio/d10.mp3",
        "./res/audio/d11.mp3",
        "./res/audio/d12.mp3"};

/**
 * @brief 在后台播放一个MP3文件
 * @details 此函数构建一个shell命令，并使用 system() 调用 'mpg123' 播放器。
 * '-q' 参数使播放器以静默模式运行（不输出额外信息）。
 * '-o alsa' 参数指定音频输出到 ALSA (Advanced Linux Sound Architecture) 设备。
 * '&' 使命令在后台执行，这样可以立即返回，不会阻塞当前程序的执行。
 * @param index 要播放的MP3文件在 `mp3_file` 数组中的索引 (有效范围 0-11)。
 */
void play_mp3(int index)
{
    // 边界检查，确保传入的索引是有效的，防止数组越界访问
    if (index >= 0 && index < 12)
    {
        // 定义一个字符数组作为缓冲区，用于存储将要执行的shell命令
        char command[128]; // 预留足够空间以防止路径过长导致溢出

        // 使用 sprintf 格式化字符串，构建完整的命令行指令
        // 例如，当 index 为 0 时, command 将变为 "mpg123 -q -o alsa ./res/audio/d1.mp3 &"
        sprintf(command, "mpg123 -q -o alsa %s &", mp3_file[index]);

        // 调用 system() 函数在操作系统的shell中执行该命令
        // 这是与外部程序交互的一种简单方式
        system(command);
    }
    else
    {
        // 如果索引无效，可以打印一条错误信息，便于调试
        fprintf(stderr, "Error: Invalid MP3 index %d.\n", index);
    }
}